fix(images): backport the image[] and mask[] form key drop to rc/1.102.0 (#39512) by mateo-berri · Pull Request #41697 · BerriAI/litellm

mateo-berri · 2026-09-17T23:26:32Z

TLDR

Backport of #39512 onto rc/1.102.0, so Saturday's stable v1.102.0 carries the fix (cherry-pick of merge commit 289c52b, applied clean, no rc-only changes)

Problem this solves:

/v1/images/edits forwarded the raw image[] key to providers
OpenAI 400s the documented alias: "Invalid type for 'image[0]'"
mask[] 400s the same way: "This parameter already has a different value"
v1.102.0-rc.2, the current rc tip, still carries the regression

How it solves it:

Drop image[] and mask[] from what gets forwarded
The handler already folded them into image and mask
Provider-agnostic: no OpenAI special-casing
Brings the three regression tests from fix(images): stop forwarding the raw image[] and mask[] form keys #39512 along

User Flow

Before: a developer following LiteLLM's own documented image[] form gets a 400 and no edited image

They send POST https://litellm-domain/v1/images/edits with model=gpt-image-1, image[]=@tree.png, and prompt=add a small red hat on top, exactly the form the endpoint's own docs show
They get back HTTP 400: Invalid type for 'image[0]': expected a file, but got a string instead.
They drop the brackets and send the same request with image=@tree.png, which returns HTTP 200 with an edited image
They add a mask the documented way, sending image=@tree.png plus mask[]=@mask.png, and get back HTTP 400: Invalid parameter: 'mask'. This parameter already has a different value in your parameters.
They drop those brackets too and send mask=@mask.png, which returns HTTP 200, so the documented bracketed form is unusable through the gateway on either field

After: the same documented image[] and mask[] requests come back with an edited image

They send POST https://litellm-domain/v1/images/edits with model=gpt-image-1, image[]=@tree.png, and prompt=add a small red hat on top, exactly the form the endpoint's own docs show
They get back HTTP 200 with a b64_json image and a usage block
They send the same request with image=@tree.png, which returns HTTP 200 with an edited image
They add a mask the documented way, sending image=@tree.png plus mask[]=@mask.png, and get back HTTP 200 with an edited image
They send mask=@mask.png instead and get HTTP 200 as well, so both spellings work on both fields
Sending image and image[] together still returns HTTP 422 Cannot specify both 'image' and 'image[]', so the existing guard against ambiguous requests is unchanged

Relevant issues

Backport of #39512, which fixes #41421

Affected release

regression in v1.100.0 (PR #38104), still present in v1.102.0-rc.2. #39512 carries the backport-stable label and this PR is that cherry-pick onto rc/1.102.0, so the fix lands before the stable is tagged

Linear ticket

Resolves LIT-6816

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

I have added meaningful tests
The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.); the three red CircleCI jobs are rc-line test rot, see Caveats
My PR's scope is as isolated as possible; it only solves 1 specific problem
I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Both legs run on the rc line: Before is the rc/1.102.0 tip 3f965660a1 (what v1.102.0-rc.2 ships), After is this PR's tip 0e03b62ab8. Same proxy config against the real OpenAI API with gpt-image-2.5-sunburst, two uvicorn workers (--num_workers 2) on each proxy, and the same 256x256 tree.png / tree2.png / tree3.png / mask.png set as #39512's run on main. The customer's own call shape is the OpenAI Python SDK's client.images.edit(image=[...]), which the SDK sends as repeated image[] parts, so the SDK cases come first and the curl cases cover the documented bracketed forms directly. Real spend on every 200. Same nine cases in the same order on both sides

config.yaml:

model_list:
  - model_name: gpt-image-2.5-sunburst
    litellm_params:
      model: openai/gpt-image-2.5-sunburst
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: sk-lit6816

sdk_edit.py:

import sys, json
from openai import OpenAI, APIStatusError
base_url, model, mode = sys.argv[1], sys.argv[2], sys.argv[3]
client = OpenAI(base_url=base_url, api_key="sk-lit6816")
files = {"single": open("tree.png", "rb"), "list1": [open("tree.png", "rb")], "list3": [open("tree.png", "rb"), open("tree2.png", "rb"), open("tree3.png", "rb")]}[mode]
try:
    r = client.images.edit(model=model, image=files, prompt="add a small red hat on top of the tree", size="1024x1024", quality="low")
    print(json.dumps({"created": r.created, "usage_total_tokens": r.usage.total_tokens if r.usage else None, "b64_json_length": len(r.data[0].b64_json or "")}))
except APIStatusError as e:
    print(f"HTTP {e.status_code}", json.dumps(e.body)[:400])

Each case is the command followed by its output. A 200 is summarized to created, usage.total_tokens, the b64_json length, and the number of images returned; an error shows the proxy's response body

Before (`3f96566`)

SDK: three images in a list (the customer flow)

$ python sdk_edit.py http://127.0.0.1:PORT gpt-image-2.5-sunburst list3   # OpenAI SDK: client.images.edit(model=..., image=<list3>, prompt=..., size="1024x1024", quality="low")
HTTP 400 {"message": "litellm.BadRequestError: OpenAIException - {\n  \"error\": {\n    \"message\": \"Invalid type for 'image[0]': expected a file, but got a string instead.\",\n    \"type\": \"invalid_request_error\",\n    \"param\": \"image[0]\",\n    \"code\": \"invalid_type\"\n  }\n}. Received Model Group=gpt-image-2.5-sunburst\nAvailable Model Group Fallbacks=None", "type": "invalid_request_error", "

SDK: a list of one image

$ python sdk_edit.py http://127.0.0.1:PORT gpt-image-2.5-sunburst list1   # OpenAI SDK: client.images.edit(model=..., image=<list1>, prompt=..., size="1024x1024", quality="low")
HTTP 400 {"message": "litellm.BadRequestError: OpenAIException - {\n  \"error\": {\n    \"message\": \"Invalid type for 'image[0]': expected a file, but got a string instead.\",\n    \"type\": \"invalid_request_error\",\n    \"param\": \"image[0]\",\n    \"code\": \"invalid_type\"\n  }\n}. Received Model Group=gpt-image-2.5-sunburst\nAvailable Model Group Fallbacks=None", "type": "invalid_request_error", "

SDK: a single image, not a list

$ python sdk_edit.py http://127.0.0.1:PORT gpt-image-2.5-sunburst single   # OpenAI SDK: client.images.edit(model=..., image=<single>, prompt=..., size="1024x1024", quality="low")
{"created": 1789687525, "usage_total_tokens": 478, "b64_json_length": 1145840}

curl: two image[] parts

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image[]=@tree.png" -F "image[]=@tree2.png" -F "size=1024x1024" -F "quality=low"
HTTP 400 {"error": {"message": "litellm.BadRequestError: OpenAIException - {\n  \"error\": {\n    \"message\": \"Invalid type for 'image[0]': expected a file, but got a string instead.\",\n    \"type\": \"invalid_request_error\",\n    \"param\": \"image[0]\",\n    \"code\": \"invalid_type\"\n  }\n}. Received Model Group=gpt-image-2.5-sunburst\nAvailable Model Group Fallbacks=None", "type": "invalid_request

curl: one image[] part

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image[]=@tree.png" -F "size=1024x1024" -F "quality=low"
HTTP 400 {"error": {"message": "litellm.BadRequestError: OpenAIException - {\n  \"error\": {\n    \"message\": \"Invalid type for 'image[0]': expected a file, but got a string instead.\",\n    \"type\": \"invalid_request_error\",\n    \"param\": \"image[0]\",\n    \"code\": \"invalid_type\"\n  }\n}. Received Model Group=gpt-image-2.5-sunburst\nAvailable Model Group Fallbacks=None", "type": "invalid_request

curl: canonical image part

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687534, "usage_total_tokens": 478, "b64_json_length": 1140288, "images": 1}

curl: image plus mask[]

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "mask[]=@mask.png" -F "size=1024x1024" -F "quality=low"
HTTP 400 {"error": {"message": "litellm.BadRequestError: OpenAIException - {\n  \"error\": {\n    \"message\": \"Invalid parameter: 'mask'. This parameter already has a different value in your parameters. Please check your parameters.\",\n    \"type\": \"invalid_request_error\",\n    \"param\": \"mask\",\n    \"code\": \"invalid_parameter\"\n  }\n}. Received Model Group=gpt-image-2.5-sunburst\nAvailable Mo

curl: image plus canonical mask

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "mask=@mask.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687545, "usage_total_tokens": 478, "b64_json_length": 1113548, "images": 1}

curl: image and image[] in one request (rejected on both sides)

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "image[]=@tree2.png" -F "size=1024x1024" -F "quality=low"
HTTP 422 {"detail": "Cannot specify both 'image' and 'image[]'"}

After (`0e03b62`)

The tip has since moved to 24d4453, which only adds a pytest.MonkeyPatch annotation on the three backported tests, so it cannot change proxy behavior and the run above still stands

SDK: three images in a list (the customer flow)

$ python sdk_edit.py http://127.0.0.1:PORT gpt-image-2.5-sunburst list3   # OpenAI SDK: client.images.edit(model=..., image=<list3>, prompt=..., size="1024x1024", quality="low")
{"created": 1789687397, "usage_total_tokens": 1010, "b64_json_length": 1142456}

SDK: a list of one image

$ python sdk_edit.py http://127.0.0.1:PORT gpt-image-2.5-sunburst list1   # OpenAI SDK: client.images.edit(model=..., image=<list1>, prompt=..., size="1024x1024", quality="low")
{"created": 1789687411, "usage_total_tokens": 478, "b64_json_length": 1145692}

SDK: a single image, not a list

$ python sdk_edit.py http://127.0.0.1:PORT gpt-image-2.5-sunburst single   # OpenAI SDK: client.images.edit(model=..., image=<single>, prompt=..., size="1024x1024", quality="low")
{"created": 1789687422, "usage_total_tokens": 478, "b64_json_length": 1125640}

curl: two image[] parts

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image[]=@tree.png" -F "image[]=@tree2.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687432, "usage_total_tokens": 744, "b64_json_length": 1137656, "images": 1}

curl: one image[] part

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image[]=@tree.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687441, "usage_total_tokens": 478, "b64_json_length": 1141424, "images": 1}

curl: canonical image part

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687452, "usage_total_tokens": 478, "b64_json_length": 1140744, "images": 1}

curl: image plus mask[]

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "mask[]=@mask.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687462, "usage_total_tokens": 478, "b64_json_length": 1124220, "images": 1}

curl: image plus canonical mask

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "mask=@mask.png" -F "size=1024x1024" -F "quality=low"
HTTP 200 {"created": 1789687473, "usage_total_tokens": 478, "b64_json_length": 1122276, "images": 1}

curl: image and image[] in one request (rejected on both sides)

$ curl -s http://127.0.0.1:PORT/v1/images/edits -H "Authorization: Bearer sk-lit6816" -F "model=gpt-image-2.5-sunburst" -F "prompt=add a small red hat on top of the tree" -F "image=@tree.png" -F "image[]=@tree2.png" -F "size=1024x1024" -F "quality=low"
HTTP 422 {"detail": "Cannot specify both 'image' and 'image[]'"}

Type

🐛 Bug Fix

Caveats (if any)

Low

Only OpenAI was driven live on the rc line
- fix(images): stop forwarding the raw image[] and mask[] form keys #39512 also drove Gemini on main; no provider transformation reads the dropped keys
Indexed image[0] parts still 500 on both sides
- Undocumented spelling, left alone here as on main
The three red CircleCI jobs at this tip are rc-line test rot, not this PR
- local_testing_part1 (3), local_testing_part2 (1), llm_translation_testing (18) fail only on live Together AI tests
- All 22 failures hit openai/gpt-oss-20b, a serverless model Together retired
- main dropped those live tests in test(together_ai): move request-shape checks to the mapped file, drop the live ones #41360 (merged Wed, Sep 16); rc/1.102.0 predates it
- This PR touches only the image edits endpoint and its unit test
- rc/1.102.0 never runs CircleCI on its own, so this pipeline is the rc line's only signal

Final Attestation

The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

…2.0 (#39512) (cherry picked from commit 289c52b)

greptile-apps · 2026-09-17T23:29:11Z

Confidence Score: 5/5

The PR appears safe to merge; no actionable issue remains in the reviewed changes.

Summary

This backport prevents normalized image[] and mask[] multipart aliases from also being forwarded to image providers under their bracketed keys.

Introduces shared constants for bracketed image-edit file fields.
Filters bracketed aliases from provider-bound request data while retaining canonical image and mask content.
Adds regression coverage for bracketed aliases and canonical file fields.
The changes since the previous review strongly type all three new monkeypatch parameters, fully addressing the resolved prior finding.

_{Reviews (2) · Last reviewed commit: "test(images): type the monkeypatch fixtu..."}

mateo-berri · 2026-09-17T23:34:41Z

@greptileai

mateo-berri · 2026-09-17T23:40:06Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 24d4453. Configure here.}

fix(images): backport the image[] and mask[] form key drop to rc/1.10…

0e03b62

…2.0 (#39512) (cherry picked from commit 289c52b)

mateo-berri added the run-ci label Sep 17, 2026

greptile-apps Bot reviewed Sep 17, 2026

View reviewed changes

Comment thread tests/test_litellm/proxy/image_endpoints/test_endpoints.py Outdated

test(images): type the monkeypatch fixture on the backported edit tests

24d4453

mateo-berri added run-ci and removed run-ci labels Sep 17, 2026

cursor Bot reviewed Sep 17, 2026

View reviewed changes

mateo-berri merged commit e1ef8b3 into rc/1.102.0 Sep 17, 2026
52 of 56 checks passed

mateo-berri deleted the litellm_backport_39512_rc_1_102_0 branch September 17, 2026 23:58

mateo-berri mentioned this pull request Sep 19, 2026

fix(proxy): keep image-edit uploads as files instead of strings #41864

Closed

Navigation Menu

Repository navigation

fix(images): backport the image[] and mask[] form key drop to rc/1.102.0 (#39512) - #41697

fix(images): backport the image[] and mask[] form key drop to rc/1.102.0 (#39512)#41697
mateo-berri merged 2 commits into
rc/1.102.0from
litellm_backport_39512_rc_1_102_0

mateo-berri commented Sep 17, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

mateo-berri commented Sep 17, 2026

Uh oh!

mateo-berri commented Sep 17, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mateo-berri commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TLDR

User Flow

Relevant issues

Affected release

Linear ticket

Pre-Submission checklist

Delays in PR merge?

Screenshots / Proof of Fix

Before (3f96566)

SDK: three images in a list (the customer flow)

SDK: a list of one image

SDK: a single image, not a list

curl: two image[] parts

curl: one image[] part

curl: canonical image part

curl: image plus mask[]

curl: image plus canonical mask

curl: image and image[] in one request (rejected on both sides)

After (0e03b62)

SDK: three images in a list (the customer flow)

SDK: a list of one image

SDK: a single image, not a list

curl: two image[] parts

curl: one image[] part

curl: canonical image part

curl: image plus mask[]

curl: image plus canonical mask

curl: image and image[] in one request (rejected on both sides)

Type

Caveats (if any)

Low

Final Attestation

Uh oh!

greptile-apps Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Uh oh!

Uh oh!

mateo-berri commented Sep 17, 2026

Uh oh!

mateo-berri commented Sep 17, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mateo-berri commented Sep 17, 2026 •

edited

Loading

Before (`3f96566`)

After (`0e03b62`)

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading